<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- states.qdoc -->
  <title>Qt Quick States | Qt Quick 5.12.3</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="../qtdoc/index.html">Qt 5.12</a></td><td ><a href="qtquick-index.html">Qt Quick 模块</a></td><td >Qt Quick States</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtquick-index.html">Qt 5.12.3 参考指南</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">目录</a></h3>
<ul>
<li class="level1"><a href="#related-types">Related Types</a></li>
<li class="level1"><a href="#creating-states">Creating States</a></li>
<li class="level1"><a href="#the-default-state">The Default State</a></li>
<li class="level1"><a href="#the-when-property">The <code>when</code> Property</a></li>
<li class="level1"><a href="#animating-state-changes">Animating State Changes</a></li>
<li class="level1"><a href="#state-fast-forwarding">State Fast Forwarding</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Quick States</h1>
<span class="subtitle"></span>
<!-- $$$qtquick-statesanimations-states.html-description -->
<div class="descr"> <a name="details"></a>
<a name="related-types"></a>
<h2 id="related-types">Related Types</h2>
<div class="table"><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtquick-anchorchanges.html">AnchorChanges</a></p></td><td class="tblDescr"><p>Specifies how to change the anchors of an item in a state</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtquick-parentchange.html">ParentChange</a></p></td><td class="tblDescr"><p>Specifies how to reparent an Item in a state change</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></p></td><td class="tblDescr"><p>Describes new property bindings or values for a state</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtquick-state.html">State</a></p></td><td class="tblDescr"><p>Defines configurations of objects and properties</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qml-qtquick-statechangescript.html">StateChangeScript</a></p></td><td class="tblDescr"><p>Specifies how to run a script in a state</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qml-qtquick-stategroup.html">StateGroup</a></p></td><td class="tblDescr"><p>Provides built-in state support for non-Item types</p></td></tr>
</table></div>
<p>Many user interface designs are <i>state driven</i>; interfaces have configurations that differ depending on the current state. For example, a traffic signal will configure its flags or lights depending on its state. While in the signal's <code>stop</code> state, a red light will turn on while the yellow and the green lights will turn off. In the <code>caution</code> state, the yellow light is on while the other lights are turned off.</p>
<p>In QML, <i>states</i> are a set of property configurations defined in a <a href="qml-qtquick-state.html">State</a> type. Different configurations could, for example:</p>
<ul>
<li>Show some UI components and hide others</li>
<li>Present different available actions to the user</li>
<li>Start, stop, or pause animations</li>
<li>Execute some script required in the new state</li>
<li>Change a property value for a particular item</li>
<li>Show a different view or screen</li>
</ul>
<p>All <a href="qml-qtquick-item.html">Item</a>-based objects have a <code>state</code> property, and can specify additional states by adding new <code>State</code> objects to the item's <a href="qml-qtquick-item.html#states-prop">states</a> property. Each state within a component has a unique <code>name</code>, an empty string being the default. To change the current state of an item, set the <a href="qml-qtquick-item.html#state-prop">state</a> property to the name of the state.</p>
<p>Non-Item objects may use states through the <a href="qml-qtquick-stategroup.html">StateGroup</a> type.</p>
<a name="creating-states"></a>
<h2 id="creating-states">Creating States</h2>
<p>To create a state, add a <a href="qml-qtquick-state.html">State</a> object to the item's <a href="qml-qtquick-item.html#states-prop">states</a> property, which holds a list of states for that item.</p>
<p>A warning <code>signal</code> component may have two states, the <code>NORMAL</code> and the <code>CRITICAL</code> state. Suppose that in the <code>NORMAL</code> state, the <code>color</code> of the signal should be <code>green</code> and the warning <code>flag</code> is down. Meanwhile, in the <code>CRITICAL</code> state, the <code>color</code> should be <code>red</code> and the flag is <code>up</code>. We may model the states using the <code>State</code> type and the color and flag configurations with the <code>PropertyChanges</code> type.</p>
<pre class="qml">

  <span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">id</span>: <span class="name">signal</span>
      <span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">200</span>
      <span class="name">state</span>: <span class="string">&quot;NORMAL&quot;</span>

      <span class="name">states</span>: [
          <span class="type"><a href="qml-qtquick-state.html">State</a></span> {
              <span class="name">name</span>: <span class="string">&quot;NORMAL&quot;</span>
              <span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">signal</span>; <span class="name">color</span>: <span class="string">&quot;green&quot;</span>}
              <span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">flag</span>; <span class="name">state</span>: <span class="string">&quot;FLAG_DOWN&quot;</span>}
          },
          <span class="type"><a href="qml-qtquick-state.html">State</a></span> {
              <span class="name">name</span>: <span class="string">&quot;CRITICAL&quot;</span>
              <span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">signal</span>; <span class="name">color</span>: <span class="string">&quot;red&quot;</span>}
              <span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">flag</span>; <span class="name">state</span>: <span class="string">&quot;FLAG_UP&quot;</span>}
          }
      ]
  }

</pre>
<p>The <a href="qml-qtquick-propertychanges.html">PropertyChanges</a> type will change the values of object properties. Objects are referenced through their <a href="../qtqml/qtqml-syntax-objectattributes.html">id</a>. Objects outside the component are also referenced using the <code>id</code> property, exemplified by the property change to the external <code>flag</code> object.</p>
<p>Further, the state may change by assigning the <code>state</code> property with the appropriate signal state. A state switch could be in a <a href="qml-qtquick-mousearea.html">MouseArea</a> type, assigning a different state whenever the signal receives a mouse click.</p>
<pre class="qml">

  <span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">id</span>: <span class="name">signalswitch</span>
      <span class="name">width</span>: <span class="number">75</span>; <span class="name">height</span>: <span class="number">75</span>
      <span class="name">color</span>: <span class="string">&quot;blue&quot;</span>

      <span class="type"><a href="qml-qtquick-mousearea.html">MouseArea</a></span> {
          <span class="name">anchors</span>.fill: <span class="name">parent</span>
          <span class="name">onClicked</span>: {
              <span class="keyword">if</span> (<span class="name">signal</span>.<span class="name">state</span> <span class="operator">==</span> <span class="string">&quot;NORMAL&quot;</span>)
                  <span class="name">signal</span>.<span class="name">state</span> <span class="operator">=</span> <span class="string">&quot;CRITICAL&quot;</span>
              <span class="keyword">else</span>
                  <span class="name">signal</span>.<span class="name">state</span> <span class="operator">=</span> <span class="string">&quot;NORMAL&quot;</span>
          }
      }
  }

</pre>
<p>The State type is not limited to performing modifications on property values. It can also:</p>
<ul>
<li>Run some script using <a href="qml-qtquick-statechangescript.html">StateChangeScript</a></li>
<li>Override an existing signal handler for an object using <a href="qml-qtquick-propertychanges.html">PropertyChanges</a></li>
<li>Re-parent an <a href="qml-qtquick-item.html">Item</a> using <a href="qml-qtquick-parentchange.html">ParentChange</a></li>
<li>Modify anchor values using <a href="qml-qtquick-anchorchanges.html">AnchorChanges</a></li>
</ul>
<a name="the-default-state"></a>
<h2 id="the-default-state">The Default State</h2>
<p>Every <a href="qml-qtquick-item.html">Item</a> based component has a <code>state</code> property and a <i>default state</i>. The default state is the empty string (<code>&quot;&quot;</code>) and contains all of an item's initial property values. The default state is useful for managing property values before state changes. Setting the <code>state</code> property to an empty string will load the default state.</p>
<a name="the-when-property"></a>
<h2 id="the-when-property">The <code>when</code> Property</h2>
<p>For convenience, the <a href="qml-qtquick-state.html">State</a> type has a <code>when</code> property that can bind to expressions to change the state whenever the bound expression evaluates to <code>true</code>. The <code>when</code> property will revert the state back to the <a href="qtquick-statesanimations-states.html#the-default-state">default state</a> when the expression evaluates to false.</p>
<pre class="qml">

  <span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">id</span>: <span class="name">bell</span>
      <span class="name">width</span>: <span class="number">75</span>; <span class="name">height</span>: <span class="number">75</span>
      <span class="name">color</span>: <span class="string">&quot;yellow&quot;</span>

      <span class="name">states</span>: <span class="name">State</span> {
                  <span class="name">name</span>: <span class="string">&quot;RINGING&quot;</span>
                  <span class="name">when</span>: (<span class="name">signal</span>.<span class="name">state</span> <span class="operator">==</span> <span class="string">&quot;CRITICAL&quot;</span>)
                  <span class="type"><a href="qml-qtquick-propertychanges.html">PropertyChanges</a></span> {<span class="name">target</span>: <span class="name">speaker</span>; <span class="name">play</span>: <span class="string">&quot;RING!&quot;</span>}
              }
  }

</pre>
<p>The <code>bell</code> component will change to the <code>RINGING</code> state whenever the <code>signal.state</code> is <code>CRITICAL</code>.</p>
<a name="animating-state-changes"></a>
<h2 id="animating-state-changes">Animating State Changes</h2>
<p>State changes induce abrupt value changes. The <a href="qmlexampletoggleswitch.html#transition">Transition</a> type allow smoother changes during state changes. In transitions, animations and interpolation behaviors are definable. The <a href="qtquick-statesanimations-animations.html">Animation and Transitions</a> article has more information about creating state animations.</p>
<p>The <a href="qtquick-animation-example.html">Animation</a> example demonstrates how to declare a basic set of states and apply animated transitions between them.</p>
<p><a href="qtquick-statesanimations-behaviors.html">Using Qt Quick Behaviors with States</a> explains a common problem when using Behaviors to animate state changes.</p>
<a name="state-fast-forwarding"></a>
<h2 id="state-fast-forwarding">State Fast Forwarding</h2>
<p>In order for Transition to correctly animate state changes, it is sometimes necessary for the engine to fast forward and rewind a state (that is, internally set and unset the state) before it is finally applied. The process is as follows:</p>
<ol class="1" type="1"><li>The state is fast forwarded to determine the complete set of end values.</li>
<li>The state is rewound.</li>
<li>The state is fully applied, with transitions.</li>
</ol>
<p>In some cases this may cause unintended behavior. For example, a state that changes a view's <i>model</i> or a Loader's <i>sourceComponent</i> will set these properties multiple times (to apply, rewind, and then reapply), which can be relatively expensive.</p>
<p>State fast forwarding should be considered an implementation detail, and may change in later versions.</p>
</div>
<!-- @@@qtquick-statesanimations-states.html -->
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br/>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br/>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
